'\" te
.\"  Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH VARARGS 3EXT "May 10, 2002"
.SH NAME
varargs \- handle variable argument list
.SH SYNOPSIS
.LP
.nf
#include <varargs.h>
va_alist
va_dcl
va_list \fIpvar\fR;

\fBvoid\fR \fBva_start\fR(\fBva_list\fR\fIpvar\fR);
.fi

.LP
.nf
\fBtype\fR \fBva_arg\fR(\fBva_list\fR \fIpvar\fR, \fB\fR\fItype\fR);
.fi

.LP
.nf
\fBvoid\fR \fBva_end\fR(\fBva_list\fR \fIpvar\fR);
.fi

.SH DESCRIPTION
.sp
.LP
This set of macros allows portable procedures that accept variable argument
lists to be written. Routines that have variable argument lists (such as
\fBprintf\fR(3C)) but do not use \fBvarargs\fR are inherently non-portable, as
different machines use different argument-passing conventions.
.sp
.LP
\fBva_alist\fR is used as the parameter list in a function header.
.sp
.LP
\fBva_dcl\fR is a declaration for \fBva_alist\fR. No semicolon should follow
\fBva_dcl\fR.
.sp
.LP
\fBva_list\fR is a type defined for the variable used to traverse the list.
.sp
.LP
\fBva_start\fR is called to initialize \fBpvar\fR to the beginning of the list.
.sp
.LP
\fBva_arg\fR will return the next argument in the list pointed to by
\fBpvar\fR. \fBtype\fR is the type the argument is expected to be. Different
types can be mixed, but it is up to the routine to know what type of argument
is expected, as it cannot be determined at runtime.
.sp
.LP
\fBva_end\fR is used to clean up.
.sp
.LP
Multiple traversals, each bracketed by \fBva_start\fR and \fBva_end\fR, are
possible.
.SH EXAMPLES
.LP
\fBExample 1 \fRA sample program.
.sp
.LP
This example is a possible implementation of \fBexecl\fR (see \fBexec\fR(2) ).

.sp
.in +2
.nf
\fB#include <unistd.h>
#include <varargs.h>
#define MAXARGS	100
/*	execl is called by
		execl(file, arg1, arg2, ..., (char *)0);
*/
execl(va_alist)
va_dcl
{
	va_list ap;
	char *file;
	char *args[MAXARGS];		/* assumed big enough*/
	int argno = 0;

	va_start(ap);
	file = va_arg(ap, char *);
	while ((args[argno++] = va_arg(ap, char *)) != 0)
		;
	va_end(ap);
	return execv(file, args);
}\fR
.fi
.in -2
.sp

.SH SEE ALSO
.sp
.LP
.BR exec (2),
.BR printf (3C),
.BR vprintf (3C),
.BR stdarg (3EXT)
.SH NOTES
.sp
.LP
It is up to the calling routine to specify in some manner how many arguments
there are, since it is not always possible to determine the number of arguments
from the stack frame. For example, \fBexecl\fR is passed a zero pointer to
signal the end of the list. \fBprintf\fR can tell how many arguments are there
by the format.
.sp
.LP
It is non-portable to specify a second argument of \fBchar\fR, \fBshort\fR, or
\fBfloat\fR to \fBva_arg\fR, since arguments seen by the called function are
not \fBchar\fR, \fBshort\fR, or \fBfloat\fR. C converts \fBchar\fR and
\fBshort\fR arguments to \fBint\fR and converts \fBfloat\fR arguments to
\fBdouble\fR before passing them to a function.
.sp
.LP
\fBstdarg\fR is the preferred interface.
